/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package main.KBProcess;

import java.io.Serializable;
import main.NER.Trie.ContextTrie.ORIENTATION;
import main.Ontology.ElementOntologySet;

/**
 * The smallest unit of the KB considered during entity recognition called fragment consist of an entity and its surrounding contexts
 * @author Isaac Osesina
 */
public interface Fragment extends Serializable, Comparable<Object>, Cloneable {

    /**
     * Gets id of this fragment
     * Fragment id is only unique within NER_KB (Knowledgebase)
     * @return fragment id
     */
    int getSequenceNum();

    /**
     * Return the Label (Type name) of entity belonging to this fragment
     * @return Element.Context if ElementType=CONTEXT otherwise element tag e.g. Name, Date
     */
    String getEntityLabel();

    /**
     * Returns the id number of the EntityLabel. Id is obtained from the document ontology
     * @return id number of the EntityLabel
     */
    int getEntityLabelIndex();

    /**
     * Return left context: string preceding an annotated entity type
     * @return left context
     */
    String getLeftContext();

    /**
     * Return right context: string following an annotated entity type
     * @return right context
     */
    String getRightContext();

    /**
     * Returns document id where fragment originated
     * @return document id
     */
    int getDocID();

    /**
     * Returns document label (type/name) where fragment originated
     * @return document label (type/name)
     */
    String getDocumentLabel();

    /**
     * Returns the sequence number of fragment within originating document
     * This is equal to the SequenceNumInDoc of associated entity
     * @return sequence number of fragment within originating document
     */
    int getFragmentPosInDoc();


    /**
     * Sets id of this fragment
     * Fragment id must be unique within NER_KB (Knowledgebase)
     * @param id fragment id
     */
    void setSequenceNum(int id);

    /**
     * Returns the name of the language of the document from which Fragment originated
     * @return name of the language of the document from which Fragment originated
     */
    String getLanguageType();

    /**
     *
     * @return return String.format("FragID:%d|DocID:%d|DocType:%s|ETypeIndex:%d|LCxt:%s|eType:<%s>|RCxt:%s",
                      id, documentID, documentLabel, entityLabelIndex, leftContext, entityLabel, rightContext);
     */
    @Override
    String toString();
    /**
     * 
     * @return String.format("%d %d %s %d {%s}<%s>{%s}",
                      id, documentID, documentLabel, entityLabelIndex, leftContext, entityLabel, rightContext)
     */
    String toStringRow();

    /**
     * Sets the <code>Element</code> containing the Left Context of this fragment
     * @param element <code>Element</code> containing the Left Context of this fragment
     */
    public void setLeftElement(Element element);

    /**
     * Sets the <code>Element</code> containing the Right Context of this fragment
     * @param element <code>Element</code> containing the Right Context of this fragment
     */
    public void setRightElement(Element element);

    /**
     * Sets the <code>Element</code> containing the Entity of this fragment
     * @param element <code>Element</code> containing the Entity of this fragment
     */
    public void setEntityElement(Element element);

    /**
     * Returns the <code>Element</code> containing the Left Context of this fragment
     * @return the <code>Element</code> containing the Left Context of this fragment
     */
    public Element getLeftElement();

    /**
     * Returns the <code>Element</code> containing the Right Context of this fragment
     * @return the <code>Element</code> containing the Right Context of this fragment
     */
    public Element getRightElement();

    /**
     * Returns the <code>Element</code> containing the Entity of this fragment
     * @return the <code>Element</code> containing the Entity value of this fragment
     */
    public Element getEntityElement();
    
    /**
     * 
     * @param orientation ORIENTATION.LEFT or ORIENTATION.RIGHT to indicate which context is to be returned
     * In the case of orientation = ORIENTATION.LEFT, this methods behave like getLeftContext()
     * In the case of orientation = ORIENTATION.RIGHT, this methods behave like getRightContext()
     * @return left or right context of fragment
     */
    public Element getContextElement( ORIENTATION orientation );
    
    /**
     * Returns the ElementOntologySet of the entity contained in this fragment
     * @return the ElementOntologySet of the entity contained in this fragment
     */
    public ElementOntologySet getOntologies();
    
    /**
     * Returns the ElementOntologySet of the entity contained in the preceeding fragment
     * returns null if this is first fragment in the document
     * @return ElementOntologySet of the entity contained in the preceeding fragment
     * returns null if this is first fragment in the document
     */
    public ElementOntologySet getPreFragmentOntologies();
    
    /**
     * Returns the ElementOntologySet of the entity contained in the next fragment
     * returns null if this is last fragment in the document
     * @return ElementOntologySet of the entity contained in the next fragment
     * returns null if this is last fragment in the document
     */
    public ElementOntologySet getPostFragmentOntologies();

}
